Comments should be sent to AppleLink address OPENTPT or Internet address 'opentpt@applelink.apple.com' Unfortunately, we can not provide general technical support via this AppleLink address. Technical support questions should be directed to AppleLink address DEVSUPPORT or Internet address 'devsupport@applelink.apple.com'.
Overview
This is a development release of Open Transport for AppleTalk and TCP/IP.
This release includes an AppleTalk Phase 2 stack containing PAP, ADSP, ATP, DDP and below. It includes a TCP/IP stack containing TCP, UDP, IP and a DNR. More information on the particular capabilities of these two stacks are contained in documentation specific to AppleTalk or TCP/IP (see below).
What this release contains
This release includes
• an Installer that will install Open Transport 1.1b14 and Apple Shared Library Manager 2.0 onto your machine.
• a Developer Files folder that contains:
• An ASLM Developer folder contain tools for developing ASLM shared libraries, as well as debugging versions of the Shared Library Manager itself.
• An Open Tpt Client Developer folder that contains documents, header files, MPW libraries, and sample programs
WARNINGS
See also the ReadMe file that accompanies Open Transport
• If you have installed the debug version of OpenTransport on a NuBus Power Macintosh, you will ALWAYS get 2 UserBreaks when booting your machine. The first UserBreak will have no text associated with it, while the second will have the text "TLibrary::PrivateLoadSegment- Loading a Segment failed". Please do not report these as bugs.
Development Information
This developer kit was created using the pre-release MPW environment from E.T.O. #18
IMPORTANT DEVELOPER WARNING!!!
The 68K libraries for version 1.1b1 through 1.1b5 were incompatible with the libraries from the 1.0.6/1.0.7 Open Transport releases. Because some developers have released 68K products with the libraries of these releases, it has been decided that we should modify the 1.1 68K libraries to insure compatibility with the those libraries. Because of this, any 68K code linked with the 1.1b1 through 1.1b5 libraries will not be compatible with the final 1.1 Open Transport product. The libraries with the 1.1b6 and later releases are compatible with the library from the 1.0.6/1.0.7 Open Transport releases, and will be compatible with the final 1.1 Open Transport product.
Linking with Open Transport Libraries:
For 68K Libraries:
You should link with OpenTptUtils.o (for model far) or OpenTptUtils.n.o (for model near) if you are writing code that is only dealing with ports. Linking with this file keeps the whole Open Transport environment from loading.
If you're not sure, try linking with this file. If you get unresolved symbols, then link with OpenTransport.o.
If you are writing an application, also link with OpenTransportApp.o (for model far) or OpenTransportApp.n.o (for model near). If you are writing a stand-alone code resource, CFM fragment, or ASLM shared library, also link with OpenTransportExtn.o (for model far) or OpenTransportExtn.n.o (for model near).
You should link with OpenTransport.o (for model far) or OpenTransport.n.o (for model near) if you are writing code that creates and uses endpoints, mappers or other providers. If you are writing an application, also link with OpenTransportApp.o (for model far) or OpenTransportApp.n.o (for model near). If you are writing a stand-alone code resource, CFM fragment, or ASLM shared library, also link with OpenTransportExtn.o (for model far) or OpenTransportExtn.n.o (for model near).
You should link with OpenTptATalk.o (for model far) or OpenTptATalk.n.o (for model near) if you are writing code that uses the AppleTalkServices provider.
You should link with OpenTptInet.o (for model far) or OpenTptInet.n.o (for model near) if you are writing code that uses the InternetServices provider.
In all cases, if you are NOT writing an appliction, but are writing a stand-alone code resource, CFM fragment, or ASLM shared library, also link with OpenTransportApp.o (for model far) or OpenTransportExtn.n.o (for model near).
If you are writing code that uses ASLM, then you should link with the ASLM libraries first, then the Open Transport libraries, ignoring any duplicate symbol definitions that occur between them.
For PPC Libraries:
You should link with OpenTransportUtilLib and OpenTptUtilsPPC.o if you are writing code that is only dealing with ports.
Linking with this file keeps the whole Open Transport environment from loading. If you're not sure, try linking with this file.
If you get unresolved symbols, then link with OpenTransportLib and OpenTransportPPC.o.
If you are writing an application, also link with OpenTptUtilsAppPPC.o. If you are writing a stand-alone code resource, CFM fragment, or ASLM shared library, link with OpenTptUtilsExtnPPC.o instead of OpenTptUtilsAppPPC.o.
You should link with OpenTransportLib and OpenTransportPPC.o if you are writing code that creates and uses endpoints, mappers, or other providers.
If you are writing an application, also link with OpenTransportAppPPC.o. If you are writing a stand-alone code resource, CFM fragment, or ASLM shared library, link with OpenTransportExtnPPC.o instead of OpenTransportAppPPC.o.
You should link with OpenTptATalkPPC.o and OpenTptAppleTalkLib if you are writing code that uses the AppleTalkServices provider, or AppleTalk utility routines
You should link with OpenTptInetPPC.o and OpenTptInternetLib if you are writing code that uses the InternetServices provider, or TCP/IP utility routines.
If you are writing code that uses ASLM, then you should link with the ASLM libraries first, then the Open Transport libraries, ignoring any duplicate symbol definitions that occur between them.
Known bugs/incompatibilities
• The settings "Load only when needed" has been disabled for AppleTalk. It is not technically feasible at this time.
• When using MacPPP, please delete all unused version of the Control Panel (ConfigPPP), extension (PPP), and preferences. Opening ConfigPPP may crash your system if it finds inappropriate PPP resources.
• When running TCP/IP over a SLIP or PPP link only, it is recommended that you leave the "Router address" and "Subnet mask" fields blank in the TCP/IP Control Panel. Since the values assigned to these by some Internet providers may in some circumstances be incompatible with Open Transport TCP/IP, Open Transport will automatically generate a default router address and subnet mask when using either a SLIP or a PPP Link if you leave these fields blank.
API changes since 1.1b11
Bug Fixes since 1.1b11
General
• Fixed several problems with unloading of code in Open Transport. This should fix many crash problems that occur when either turning AppleTalk off, or using TCP/IP in the "Load only when needed" configuration.
• Fixed a crash that occured sometimes in "mps_sqe_rip" when unloading modules.
• Fixed a crash that occured sometimes in strrchr when unloading modules.
• Fixed a few memory leaks that occured when Open Transport unloaded. These were "unload-time" leaks, so did not affect operation while Open Transport was running.
• Fixed a crash that occured at Finder startup if Open Transport didn't load because an error occurred, and an outstanding notification was pending for the user.
Backward-compatibility for AppleTalk
• The .MPP driver acts now much more like "classic" AppleTalk when opening and shutting down.
• If a "Router Up" event occurs while the .MPP driver is initializing, .MPP hangs in the open routine because it accidently made a synchronous call from within it's notifier.
• Open Transport now hides the Network control panel if Open Transport is booting, and hides the AppleTalk and TCP/IP control panels if "classic" network is booting.
• Fixed a problem with Apple Remote Access on single-port PowerBooks if you switch to Ethernet and try to use ARA.
• Fixed a problem where, under low memory conditions on a PowerPC machine, if you tried to turn AppleTalk on and it failed for lack of memory, a crash occurred.
• Fixed a crash when awakening from sleep on 68K machines.
AppleTalk
• Fixed a problem where AppleTalk could not use a port if the "other" part of an OTPortRef was non-zero.
• Fixed a problem with LocalTalk support that caused LocalTalk to eventually go deaf. Using LocalTalk with both AppleTalk and TCP/IP (MacIP) at the same time usually caused the problem to occur within minutes.
• If a "Router Up" event occurs after AppleTalk has initialized (i.e. We did not see a router while initializing), we never start the timer to time routers out, so a "Router Down" event is never generated. If the routers actually go away in this scenario, lots of problems occur, since AppleTalk still thinks there's a router and will try to contact it a lot, resulting in a highly degraded user experience.
• Fixed a problem where LocalTalk was not sending short packets when it should have been.
• Fixed a problem that caused a crash when attempting to use LocalTalk on machines that have IOP LocalTalk (machines that can use the "Serial Compatibility" control panel).
• Fixed a problem with Apple Remote Access compatibility when the AppleTalk link was LocalTalk that caused us not to see file servers on the LocalTalk wire.
Backward-compatibility for TCP/IP
• Fixed a problem where a crash occured if a client called OpenResolver and the call failed.
• An error path in the IPGetAddress call was returning an un-initialized error code, which was usually a positive number. This caused clients to hang if this call errors out (typically caused by our initial configuration of MacIP with TCP/IP set to "Load only when needed").
• Fixed a crash that occurred if a user tried to connect to a name, and they cancelled the connect before the host answers (very comment if the host can't be found).
• Fixed several problems where UDP could go deaf under certain circumstances. These problems especially affected Timbuktu, MacDNS, and Real Audio.
• Fixed a problem where, if multiple clients were using the DNR at the same time, and if they closed the DNR in the same order that they opened them, a crash would occur.
TCP/IP
• Fixed a potential crash when a native Open Transport application used the T_KEEPALIVE option on a TCP stream.
• Fixed several problems with the disconnect/reconnect logic when using SLIP or PPP MDEVs.
• Fixed a problem that caused OTResolveAddress calls to the TCP/IP protocols to return kOTNotSupportedErr.
Links
Changes since 1.1b11
General
• The unloading of the Open Transport environment was not working in previous releases. Once Open Transport loaded, it stayed loaded forever. This has been fixed, so that Open Transport will unload properly if there are no clients.
• If a client receives a kOTLookErr within their notifier, and the OTLook call is made, returning either a T_GODATA or T_GOEXDATA, and the client did not issue another OTLook to see if anything else was waiting, if a T_REPLY, T_REQUEST, or T_DATA was available, the notifier would never get called again with the event, effectively hanging the client. This has been fixed.
• Worked around a problem that occurs infrequently (but will cause a crash) if a client swaps stacks in it's notifier and calls back into Open Transport.
Backward-compatibility for AppleTalk
• Worked around a problem with PowerBook Duos so that the on-board Ethernet on the dock now appears as "built-in" instead of slot 14.
• On PowerBooks with built-in IRTalk, the default port when undocked has been changed to be LocalTalk on the serial port rather than IRTalk.
Backward-compatibility for TCP/IP
• A TCPStatus call with a NULL stream pointer will not return an error to closer emulate MacTCP's behavior (MacTCP allowed the call by accident - it was supposed to return an error, but a bug in MacTCP keeps that from occuring).
TCP/IP
• MacTCP prefs are converted to Open Transport only if an Open Transport TCP/IP preference file does not exist on the target disk.
• If there are no MacTCP prefs on the target disk, TCP/IP is installed for using MacIP in the current zone, but it is set to "Never Load". Prior to this release it was set to "Load only when needed".
• Added a notification to the user if a router is not on your own subnet, warning the user that they may not be able to communication with devices on other subnets.
• Added support for an 'opts' resource in the TCP/IP preferences. It is currently a 32-bit option. If the first bit (bit 0) of this option is set, automatic mtu discovery is disabled, causing IP to not set the "Do Not Fragment" bit in the IP header. This helps work around problems with some routers and clients that, for some unknown reason, will not accept packets with that bit set.
AppleTalk
• Fixed a problem where the AppleTalk control panel would not install over another AppleTalk control panel, if it existed.
Links
Other notes about this build.
ASLM 2.0
This build installs ASLM 2.0. If you currently have a debugging version of ASLM installed, installing the non-debug version of Open Transport will replace your debug version of ASLM with the non-debug version..
Macsbug messages
If you install the debug version of OpenTransport, there are many internal debugger breaks. You must have macsbug installed, or else if a debugger break occurs, you'll get the "bomb" box.
The Installer installs various Macsbug templates and DCMD's into your Debugger Prefs file. If you have Macsbug on the target machine, an Easy Install will automatically update the Debugger Prefs file. If you're using a newer Macsbug (6.5) which doesn't come with a Debugger Prefs file, the Installer will create a Debugger Prefs file.
There is mostly a pattern to the debugger messages that appear. Most messages have a leading 2-character code. The meanings are:
NB Nonfatal error. Dump all the registers and do a stack crawl and include the results in a bug report along with what you were doing at the time. Hit 'g' in Macsbug to continue. The machine should not crash, but it might hang.
FX Fatal error. An error that is probably fatal to the machine, but is cause by an external component, and not Open Transport itself.
NX Nonfatal error. An error occurred caused by an external component, and not Open Transport itself. Hit 'g' in Macsbug to continue. The machine should not crash, but it might hang.
UF User fatal err. A client of Open Transport did something wrong that is probably fatal. Reboot the machine.
UE User nonfatal error. A client of Open Transport did something wrong. Hit 'g' in Macsbug to continue. The machine should not crash or hang.
IE Informative error. An error occurred that should rarely happen. Hit 'g' in Macsbug to continue. The machine should not crash or hang.
IN Informative break. This is just an informational break. Hit 'g' in Macsbug to continue. The machine should not crash or hang.
Documentation
There is a "Document" folder which contains more documentation:
• Open Transport Client Note - A reference document for programmers wishing to write software using the Open Transport APIs.
• Open Tpt AppleTalk Dev Note - Material specific to AppleTalk.
• Open Tpt Serial Dev Note - Material specific to Serial endpoints.
• Open Tpt TCP/IP Dev Note - Material specific to TCP/IP.
All of these are preliminary. All of these will be worked over and turned into Apple DocViewer format documents for the final release of Open Transport 1.1.
The installer
The installer will Easy Install the Apple Shared Library Manager and Open Transport AppleTalk and TCP/IP version 1.0, as well as AppleTalk and MacTCP compatibility..
You can “undo” the AppleTalk compatibility installation by using the Network Software Installer 1.4.2 or later, and custom installing AppleTalk for System 7, Ignore any warnings it might give you about installing over a ‘newer’ AppleTalk.
This release also includes a version of MacTCP 3.0. To remove it, remove the TCP/IP Control Panel and reinstall the MacTCP control panel.
Debugger support
The installer will install Open Transport Debugger preferences into the DebuggerPrefs file in your System Folder, if you have one. These debugger prefs contain the ASLM debugger prefs plus Macsbug templates for virtually all structures used in the API. A Macbug dcmd is installed also that can display strings for error messages. For example, typing “OTErr -3158” will tell you what error number -3158 is.
Sample Code
There is a "Samples" folder which contains sample programs and source files.
All of the client samples are now Metrowerks projects (built with the Metrowerks IDE 1.3).
Earlier Release Notes
API changes since 1.1b9
• Added a T_TIMEDOUT bit to the OTFlags enumeration. This bit is set when OTRcvUReply returns 0 bytes to distinguish between a true 0-byte reply and a reply which timed out.
• Added OTScheduleInterruptTask API, which is a single call that does the equivalent of calling OTEnterInterrupt, OTScheduleDeferredTask, and OTLeaveInterrupt.
• Header files now use #if PRAGMA_ALIGN_SUPPORTED to control whether the #pragma option align=xxxx are used. In addition, the pragma option align=power is used where native PowerPC alignment is used.
Bug Fixes since 1.1b9
General
• Fixed some race conditions when streams or providers are closed. If a synchronous call was outstanding, it was possible to hang the system, and if one wasn't, it was possible to receive an event for a provider or stream that was already closed. These no longer occur.
• Fixed a problem where you could get a kOTFlowErr from an endpoint, and never receive a T_GODATA event.
• Fixed a problem where OTLook() could return 0, but a T_REQUEST event was still outstanding.
• Fixed some problems where protocols thought they were unloaded and reloaded, but their global memory was not initialized - causing erratic behavior under certain conditions.
• Fixed several problems in OTListen, where we intend to return a kOTNoDataErr, but return a kOTLookErr with a T_LISTEN event, but there is no T_LISTEN outstanding. Once this occurs, your endpoint becomes useless.
• The Open Transport Installer was clearing the System file's bundle bit. This has been fixed.
• When Open Transport scans for ports after sleep (to see if any new hardware came on-line), the resource chain was being left set to an Open Transport library, causing consternation for the frontmost application. This has been fixed.
• Fixed a problem with Open Transport going deaf and dumb under heavy load.
Backward-compatibility for AppleTalk
• Local entities are now visible when using ARA dial-up access.
• NBPLookups from outside the current zone weren't passing through the zone name that the responding entity put in the packet (depending on a zone name rather than "*" being in the zone name field violates Inside AppleTalk, but the AppleShare Print Server does not work if we don't do this).
• The machine no longer crashes in AutoRemounter if you switch links.
• Fixed a problem with random deafness - When a socket was closed, under certain circumstances AppleTalk compatibility would close a different socket than requested.
• Fixed a problem where, if an NBP name had the characters ":", "@", or "/" in the name or type fields, bad lookup data was returned to the client. This caused Chooser and Interpoll to display garbage names, which would then cause a crash if you tried to select one.
• Fixed a random crash where the .MPP compatibility driver was calling Open Transport at primary interrupt time (from the Time Manager) every 10 seconds.
AppleTalk
• When AppleTalk was closed, or the link was changed, there was a possibility of a router timeout timer firing and causing a crash. This has been fixed.
• Fixed a problem in the control panel which caused erratic behavior, because the control panel thought AppleTalk was loaded when it was not.
• Fixed several problems with AppleTalk and sleeping the machine.
• Fixed a problem where AppleTalk was writing out all of pRAM whenever the link was changed, causing spConfig to be inappropriately written out. This was causing problems for the TCP MDEV support.
• Fixed a problem where, if you switch links and fail or set a fixed address and fail, the machine becomes deaf when you return to the prior link.
• Fixed a crash which occurs if a client starts a ResolveAddress or some other name lookup on an endpoint, and then closes the endpoint.
• LocalTalk now sends short packets, when necessary. This fixes some problems with routers that refuse to answer a long packet from a local client, even though it's allowed by Inside AppleTalk.
• DDP had a bad test for a router that was inconsistent with other routers, which kept users from seeing the dialog that connectivity had changed.
• Fixed a problem in ATP, where incoming non-XO requests were always given to the client, even though the original request had not yet been replied to.
Backward-compatibility for TCP/IP
• If a hosts file is not found in the Preferences folder, the System folder is searched for the hosts file.
• Fixed a memory leak associated with listening streams (passive opens).
• Fixed a problem where, if a client started a DNR query, then closed the stream before it completed, we crashed when the answer to the query is returned by the server.
• Fixed some problems with the DNR where TCP/IP was unloading out from under it, causing a crash in certain circumstances.
• MacTCP compatibility has some sanity checks on internal data structures to try to catch when applications quit without closing all outstanding streams. These checks were not working properly, and the machine crashed if this happened. The checks are now working properly.
• Fixed a problem where TCP packets that are sent using several small fragments chained together were very slow.
• Support for RFC 793 TCP Urgent Pointer semantics was added. Previous to this build, only RFC 1123 was supported.
• Fixed a problem where, once a stream had been used by a passive open, it could not be used again for 2 minutes.
• A new csCode was added to the Open Transport MacTCP emulation to invoke the TCP_NODELAY option for use by X-Windows and other applications that send lots of small packets.
• Fixed a problem where occasionally a -19 or -21 error was returned from a MacTCP control call.
TCP/IP
• Fixed a problem where, if a client started a DNR query, then closed the stream before it completed, we crashed when the answer to the query is returned by the server.
• Fixed a problem where TCP packets that are sent using several small fragments chained together were very slow.
Links
• Fixed a problem with serial endpoints going deaf after receiving a Break on the line.
• Using Ethernet, Token Ring or FDDI on NuBus machines, any clients talking to them indirectly using Open Transport dropped lots of packets (MacIPX is an example). This has been fixed.
• Using any product that requires the Ethernet shim on PCI machines, lots of packets were lost. This has been fixed.
• Fixed a problem with the NuBus-to-Open Transport driver, where it was possible to go deaf if you used the AppleTalk control panel to switch links, the switch failed, and we revert back to the previous link.
• Fixed a problem with the NuBus-to-Open Transport driver, where a packet that has more than 32 WDS entries was truncated.
• Worked around a problem with .ENET-style drivers, where they sometimes report packets larger than the maximum size (MUCH larger - like > 32768 bytes). This caused a crash in Open Transport when using NuBus machines.
• Fixed a problem with the NuBus-to-Open Transport driver, where a packet larger than 1500 bytes was automatically treated as though it was an Ethernet DIX packet, even though we were on Token Ring or FDDI.
Changes since 1.1b9
General
• Outstanding synchronous calls are now aborted with a kOTStateChangeErr instead of a kOTCanceledErr if the provider is closed while the synchronous call is outstanding.
• OTLook() no longer returns a kOTStateChangeErr if there is an outstanding send.
• Tasks scheduled by OTScheduleDeferredTask and OTScheduleInterruptTask now run much more often.
• There are now only 2 custom packages when installing Open Transport - a 68K-only version, and an All-Macintoshes version.
• The Installer will no longer convert your MacTCP preferences to Open Transport TCP preferences, if you already have Open Transport TCP preferences.
• If a disk with Open Transport installed is booted on a system that cannot support Open Transport, Classic networking will be loaded instead.
Backward-compatibility for AppleTalk
Backward-compatibility for TCP/IP
• The MacTCP control panel is no longer required to be moved from the Control Panel folder. Open Transport now dynamically hides it or unhides depending on whether Classic network or Open Transport is booting. For those technically inclined - it is hidden by renaming it to "Classic MacTCP", setting the invisible bit, and changing the type from 'cdev' to '????'.
• Command timeouts are now a minimum of 2 seconds to properly emulate what MacTCP does.
TCP/IP
AppleTalk
• Improved the performance characteristics of native ADSP.
• PAP returns ETIMEDOUT as the reason for a disconnect if the connection timed out.
• Fixed a crash that occurs if you use the OTResolveAddress call or issue any AppleTalk call using an NBP address, and you close the endpoint before the resolution is complete.
